Skip to main content

Get Shipping Events

Method: GET
/events/shipping

As a Customer of iFoodDS, you can use the Get Ship Event API to query ship event data from the iFoodDS Trace Exchange platform.

info

This endpoint is being refined and thus subject to change. The query parameters below describe the recommended filter set for FDA traceback investigations, FSMA 204 compliance workflows, and common customer searches. Availability may depend on implementation phase. These docs will update when changes are made.

Request​

Type: application/json

Retrieving ship events via the API is done through paging. Supply optional query parameters in the request URL to select a page and filter the events returned.

Query Parameters​

All query parameters are optional. String and UUID search filters support comma-separated values as described in Multi-Value Support.

Pagination & Dates​

  • page (number): The page index of the events to return. The first page is index 0.
  • size (number): The number of results to return per page. Default value is 20.
  • submitStartDateTime (datetime): Filters results to include only events submitted after the specified date and time.
  • submitEndDateTime (datetime): Filters results to include only events submitted before the specified date and time.
  • eventStartDateTime (datetime): Filters results to include only events with an event date and time after the specified date and time.
  • eventEndDateTime (datetime): Filters results to include only events with an event date and time before the specified date and time.
  • sharedStartDateTime (datetime): Start of the date and time range when events were shared.
  • sharedEndDateTime (datetime): End of the date and time range when events were shared.

Shipment & Location Identification​

  • purchaseOrderNumber (string): Filters results to include only events exactly matching a specified purchase order number.
  • asnNumber (string): Filters results to include only events exactly matching a specified ASN (Advance Ship Notice) number.
  • billOfLadingNumber (string): Bill of lading number associated with the shipment.
  • carrierTrackingNumber (string): Carrier-assigned tracking number.
  • eventId (string): Event identifier supplied by the submitting party.
  • id (uuid): Shipping event record identifier.
  • shipToCompanyName (string): Name of the company receiving the shipment.
  • shipFromLocationCode (string): The exact ship-from vendor location code on the event.
  • shipToLocationCode (string): The exact ship-to location code on the event.
  • shipFromLocationGln (string): Global Location Number (GLN) identifying the origin location.
  • shipToLocationGln (string): Global Location Number (GLN) identifying the destination location.

Product & Item Identification​

  • vendorItemCode (string): Vendor's item code for a product in the shipment.
  • purchaserItemCode (string): Purchaser's item code for a product in the shipment.
  • caseGtin (string): Case-level Global Trade Item Number (GTIN) for a product in the shipment. Preserve leading zeros.
  • itemUpc (string): Item-level Universal Product Code (UPC). Preserve leading zeros.
  • itemPlu (string): Item-level Price Look-Up (PLU) code.
  • caseLotNumber (string): Lot number associated with a shipped product.
  • productCommodity (string): Product commodity, such as peppers.
  • productVariety (string): Product variety, such as jalapeno.
  • countryOfOrigin (string): Three-letter country code of origin of a shipped product.

FSMA 204 TLC Source & Reference​

TLC means Traceability Lot Code. Use TLC source filters to locate shipments associated with the source of a traceability lot code.

  • tlcSourceReferenceGln (string): TLC source reference Global Location Number (GLN).
  • tlcSourceReferenceDuns (string): TLC source reference Dun & Bradstreet DUNS number.
  • tlcSourceReferenceFfrn (string): TLC source reference FDA Food Facility Registration Number (FFRN).
  • tlcSourceReferenceFei (string): TLC source reference FDA Establishment Identifier (FEI).
  • tlcSourceName (string): Name of the TLC source.
  • referenceDocumentType (string): Type of reference document associated with the shipment.
  • referenceDocumentNumber (string): Number of a reference document associated with the shipment.

Sharing & Advanced Filters​

  • harvestDate (date): Harvest date of a shipped product.
  • productionDate (date): Production date of a shipped product.
  • packagingDate (date): Packaging date of a shipped product.
  • expirationDate (date): Expiration date of a shipped product.

Multi-Value Support​

For string and UUID search filters, pass multiple values as a comma-separated list in a single query parameter. Multiple values within the same parameter use OR logic: return events matching any of the supplied values.

Find shipments containing either lot
/events/shipping?caseLotNumber=LOT123,LOT456

This query returns shipments containing lot LOT123 or lot LOT456.

Find multiple events by their submitted identifiers
/events/shipping?eventId=EVENT123,EVENT456
Find multiple events by UUID
/events/shipping?id=123e4567-e89b-42d3-a456-426614174000,123e4567-e89b-42d3-a456-426614174001

Supply a single value for each pagination parameter, date-time range boundary, and date filter. Separate different query parameters with &. The OR rule above applies to values within one parameter; the ticket does not specify how different parameters are combined.

Data Constraints​

  • strings allow a maximum of 100 characters.
  • dates use the format yyyy-MM-dd.
  • datetimes use the format yyyy-MM-ddTHH:mm:ss.
  • Preserve leading zeros in identifiers such as GTINs, UPCs, and GLNs.

Request Examples​

Show everything shipped to me last week​

Use the event date-time range for the shipment period. The example below uses September 14 through September 20, 2026; replace these values with the desired week.

Shipments during a specified week
/events/shipping?eventStartDateTime=2026-09-14T00:00:00&eventEndDateTime=2026-09-20T23:59:59

Use shipToLocationCode, shipToLocationGln, or shipToCompanyName to identify a particular destination. Use the shared date-time range when searching by when an event was shared rather than when the shipment occurred. The existing event date-time filters use after/before comparisons; choose boundaries appropriate to the required investigation period.

Show all shipments containing lot ABC123​

Find a lot
/events/shipping?caseLotNumber=ABC123

Show everything from supplier XYZ​

Search by the supplier's ship-from location code or GLN. If the supplier has multiple shipping locations, supply their location codes as a comma-separated list.

Find shipments from supplier XYZ's locations
/events/shipping?shipFromLocationCode=XYZ-DC01,XYZ-DC02

Find shipments associated with a TLC source GLN​

Trace a TLC source
/events/shipping?tlcSourceReferenceGln=1234567890128

Find shipments tied to PO 12345​

Find a purchase order
/events/shipping?purchaseOrderNumber=12345

Find shipments containing GTIN 00012345678905​

Find a case GTIN
/events/shipping?caseGtin=00012345678905

Implementation Priorities​

If implementation is phased, prioritize these filters in the following order to cover the majority of FDA traceback and audit requests:

  1. purchaseOrderNumber
  2. caseLotNumber
  3. caseGtin
  4. vendorItemCode
  5. shipFromLocationCode
  6. tlcSourceReferenceGln
  7. referenceDocumentNumber
  8. asnNumber
  9. countryOfOrigin
  10. shipToCompanyName

Response​

Return result for the shipping event data queried.

{
    "content": [
        {
            "id": "<event id>",
            "eventDateTime": "<event date>",
            "purchaseOrderDate": "<purchase order date>",
            "purchaseOrderNumber": "<purchase order number>",
            "billOfLadingNumber": "<bol number>",
            "asnNumber": "<ASN (advanced shipping notice) number>",
            "expectedDeliveryDate": "<expected delivery date>",
            "shipFromLocationCode": "<ship from vendor location code>",
            "shipToLocationCode": "<ship to location code>",
            "standardCarrierAlphaCode": "<standard carrier alpha code (SCAC)>",
            "carrierShipmentMethod": "<carrier shipment method>",
            "equipmentDescription": "<equipment description>",
            "equipmentNumber": "<equipment number>",
            "appointmentNumber": "<appointment number>",
            "carrierTrackingNumber": "<carrier tracking number>",
            "loadPlanningNumber": "<load planning number>",
            "methodOfPayment": "<method of payment>",
            "shipmentLadingQuantity": "<shipment lading quantity>",
            "shipmentLadingUom": "<shipment lading unit of measure>",
            "eventTransactionTime": "<event transaction time>",
            "businessUnit": "<business unit>",
            "eventId": "<event id>",
            "productList": [
                {
                    "palletId": "<pallet id>",
                    "palletPackagingDescriptionCode": "<pallet packaging description code>",
                    "palletTiers": "<pallet tiers>",
                    "palletBlocks": "<pallet blocks>",
                    "palletLayers": "<pallet layers>",
                    "cartonsPerLayer": "<cartons per layer>",
                    "poLineNumber": "<purchase order line number>",
                    "vendorItemCode": "<vendor item code>",
                    "purchaserItemCode": "<purchaser item code>",
                    "caseGtin": "<case GTIN (Global Trade Identification Number)",
                    "caseLotNumber": "<case lot number>",
                    "shipQuantity": "<pallet quantity>",
                    "shipQuantityUom": "<ship quantity uom> (Units of Measure)",
                    "expirationDate": "<expiration date>",
                    "productionDate": "<production date>",
                    "packagingDate": "<packaging date>",
                    "bestBeforeDate": "<best before date>",
                    "harvestDate": "<harvest date>",
                    "countryOfOrigin": "<country of origin>",
                    "tlcSourceReferenceDuns": "<TLC source reference duns>",
                    "tlcSourceReferenceGln": "<TLC source reference gln>",
                    "tlcSourceReferenceFfrn": "<TLC source reference ffrn>",
                    "tlcSourceReferenceFei": "<TLC source reference fei>",
                    "tlcSourceReferenceUrl": "<TLC source reference url>",
                    "tlcSourceReferenceOther": "<TLC source reference other>",
                    "tlcSourceName": "<TLC source name>",
                    "tlcSourceAddress1": "<TLC source address 1>",
                    "tlcSourceAddress2": "<TLC source address 2>",
                    "tlcSourceCity": "<TLC source city>",
                    "tlcSourceState": "<TLC source state>",
                    "tlcSourcePostalCode": "<TLC source postal code>",
                    "tlcSourcePhoneNumber": "<TLC source phone number>",
                    "itemUpc": "<product UPC (Universal Product Code)>",
                    "itemPlu": "<product PLU>",
                    "itemDateCode": "<product date code>",
                    "itemDateCodeType": "<product date code type>"
                }
            ]
        }
    ],
    "pageable": {
        "pageNumber": <page number>,
        "pageSize": <page size>,
        "sort": {
            "unsorted": <is unsorted>,
            "sorted": <is sorted>,
            "empty": <is page empty>
        },
        "offset": <offset size>,
        "unpaged": <is unpaged>,
        "paged": <is paged>
    },
    "totalPages": <total pages>,
    "totalElements": <total elements>,
    "last": <is last page>,
    "numberOfElements": <number of elements>,
    "size": <page size>,
    "number": <page number>,
    "sort": {
        "unsorted": <is unsorted>,
        "sorted": <is sorted>,
        "empty": <is empty>
    },
    "first": <is first page>,
    "empty": <is page empty>
}

Content​

  • id (uuid): The unique id of the event
  • eventDateTime (datetime): Date and time the order was actually shipped
  • purchaseOrderDate (date): Purchase order date
  • purchaseOrderNumber (string): The purchase order number you received from your customer
  • billOfLadingNumber (string): The Bill of Lading provided by you to your customer
  • asnNumber (string): This is the unique identifier for the ASN you provide to your customer (if you provide one)
  • expectedDeliveryDate (date): Date when shipper expects to deliver goods to recipient
  • shipFromLocationCode (string): The vendor’s location code for ship from location
  • shipToLocationCode (string): The buyer’s location code for ship to location. This should be provided as part of the Purchase Order
  • standardCarrierAlphaCode (string): Standard Carrier Alpha Code (SCAC).
  • carrierShipmentMethod (string): Carrier shipment method code.
  • equipmentDescription (string): Description of the transport equipment.
  • equipmentNumber (string): Equipment identifier.
  • appointmentNumber (string): Appointment or delivery appointment number.
  • carrierTrackingNumber (string): Carrier-provided tracking number.
  • loadPlanningNumber (string): Load or load planning number.
  • methodOfPayment (string): Method of payment (e.g. PREPAID, COLLECT).
  • shipmentLadingQuantity (number): Quantity of lading units in the shipment.
  • shipmentLadingUom (string): Unit of measure for shipment lading quantity.
  • eventTransactionTime (datetime): The time the event was sent
  • businessUnit (string): The internal organizational group responsible for the event
  • eventId (string): The unique id to identify the event if provided.
  • productList (object[])
    • palletId (string): GS1 Serial Shipping Container Code, SSCC-18 (if provided)
    • palletPackagingDescriptionCode (string): Pallet packaging description code.
    • palletTiers (number): Number of tiers on the pallet.
    • palletBlocks (number): Number of blocks on the pallet.
    • palletLayers (number): Number of layers per pallet
    • cartonsPerLayer (number): Number of cartons per layer
    • poLineNumber (string): Line number in the purchase order for this item; this links the Traceability Lot Code to the line item on the PO
    • vendorItemCode (string): This is the vendor's (or your) internal product id or item code stored in their master data. If the cases shipped are labeled with a case GTIN-14, this information should be stored in the product master data record for the item code / product id referenced
    • purchaserItemCode (string): This is the purchaser's product item code provided via their PO or other form of data sharing. This information is stored in your master data. If the customer has shared a GTIN, it should be stored in the master data record. The purchaser's item code may also be the purchaser’s GTIN, but not necessarily-–it could be a SKU or another type of ID. This may point to the receiver’s master product data record
    • caseGtin (string): GTIN-14 of cases on pallet
    • caseLotNumber (string): This is the Lot Number displayed on the case label you are providing to the customer. This will be required starting in January 2026
    • shipQuantity (number): The number of units of this Traceability Lot Code on the pallet
    • shipQuantityUom (string): Unit of measure (e.g., Case)
    • expirationDate (date): The expiration date
    • productionDate (date): The production date
    • packagingDate (date): The packaging date
    • bestBeforeDate (date): The best before date
    • harvestDate (date): The harvesting date
    • countryOfOrigin (string): The three letter country code of origin
    • tlcSourceReferenceDuns (string): 9 Digit Dun & Bradstreet Number, must be registered in DUNS and available to FDA. The TLC Source reference DUNS + 4
    • tlcSourceReferenceGln (string): 13 Digit GS1 Global Location Number. Must be registered in GS1 US Data Hub | Location. The TLC Source reference GLN
    • tlcSourceReferenceFfrn (string): FDA Food Facility Registration Number, must be current in FDA Facility Regisration Database. The TLC Source reference FFRN
    • tlcSourceReferenceFei (string): FDA Establishment Identifier. This number may be requested at no cost from FDA. The TLC Source reference FEI
    • tlcSourceReferenceUrl (string): A web link point to a site where FDA may access the TLC Source Reference. The TLC Source reference URL
    • tlcSourceReferenceOther (string): This could be another identifier. One can prefix the ID with a type to make it easier to lookup. For example: 'USDAEgg: Plant 42"
    • tlcSourceName (string): The TLC source name
    • tlcSourceAddress1 (string): The TLC Source physical street address line 1 information
    • tlcSourceAddress2 (string): The TLC Source physical street address line 2 information, if applicable
    • tlcSourceCity (string): The TLC Source city location
    • tlcSourceState (string): The TLC Source state or region location
    • tlcSourcePostalCode (string): The TLC Source ZIP or postal code
    • tlcSourceCountry (string): The TLC Source country
    • tlcSourcePhoneNumber (string): The TLC Source phone number
    • itemUpc (string): Item-level Universal Product Code, may be GTIN-8, GTIN-12, or GTIN-13. GS1 GTIN Executive Summary
    • itemPlu (string): Include if items in the case are marked with PLU numbers; this may be used instead of UPC
    • itemDateCode (date): Often items are marked with a date code; if so, this field can be used to capture it
    • itemDateCodeType (string): Indicate the type of date code if provided

Pageable​

  • pageable (object)
    • pageNumber (number): The current page number in the page series. Index 0 is first page
    • pageSize (number): The number of events contained in the page
    • offset (number): If there is an offset specified on there return results this will be populates. Default is 0
    • unpaged (boolean): If the record set is unpaged then true else false
    • paged (boolean): If the record set is paged then true else false
    • sort (object)
      • unsorted (boolean): If the record set is unsorted then true else false
      • sorted (boolean): If the record set is sorted then true else false
      • empty (boolean): If the record set is empty then true else false
  • totalPages (number): The total amount of pages that contain all events in the query
  • totalElements (number): The total amount of events in the query
  • last (boolean): If the page is the last in the series then true else false
  • numberOfElements (number): The total amount of events in the table
  • size (number): The number of events contained in the page
  • number (number): The current page number in the page series
  • sort (object)
    • unsorted (boolean): If the record set is unsorted then true else false
    • sorted (boolean): If the record set is sorted then true else false
    • empty (boolean): If the record set is empty then true else false
  • first (boolean): If the page is the first in the series then true else false
  • empty (boolean): If the page is empty then true else false